## -*- mode: html; coding: utf-8; -*-

## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

<!-- WebDoc-Page-Title: BibCatalog API -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking CDS Invenio</a> -->

<pre>

BibCatalog supports "ticketing" so that cataloguers can keep track of their tasks.
Of several ticketing systems, RT (Request Tracker) is currently supported.

1. The API
bibcatalog.py consist of ticket operations, as follows.

    * check_system(uid) returns an empty string if things are OK, and an error string otherwise.
    * ticket_search(uid, recordid, subject, text, creator, owner, date_from, date_until,
                    status, priority) search tickets by various criteria.
    * ticket_submit(uid, subject, recordid, text, queue, priority, owner)
                    submit a ticket and initially set its fields.
    * ticket_assign(uid, ticketid, to_user) assign a ticket to someone.
    * ticket_set_attribute(uid, ticketid, attribute, new_value) sets an attribute.
                    These are members of TICKET_ATTRIBUTES in bibcatalog_system.py.
    * ticket_get_attribute(uid, ticketid, attrname) returns the value of an attribute.
    * ticket_get_info(uid, ticketid, attrlist) return ticket information as a dictionary.

2. Using the API

from invenio.bibcatalog import *
import sys
uid = 1 #or whatever..
x = bibcatalog_system.check_system(uid)
if len(x) > 0:
    print "errors: "+str(x)
    sys.exit()
else:
    print "ok"

3. Configuring your access to RT

Edit these lines in invenio.conf:

CFG_BIBCATALOG_SYSTEM = RT
CFG_BIBCATALOG_SYSTEM_RT_CLI = /usr/bin/rt
CFG_BIBCATALOG_SYSTEM_RT_URL = http://xxx.server.org/rt3
CFG_BIBCATALOG_QUEUES = General

Your RT installation does not need to be in the same computer where
your Invenio installation is. However, you will need the CLI (/usr/bin/rt)
Perl program.

4. Configuring RT

RT version 3 has been tested with this installation.

There are two custom fields in tickets. These should be created by the administrator by
using the "Admin/CustomFields" URL in RT. The fields are:
(i) name: RecordID - applies to: tickets
(ii) name: TicketSetID - applies to: tickets

In general, the invenio cataloguers need to have the right to submit/create tickets in the queues.
Creating users is done by RT admin using the "Admin/Users" URL.
Ticket creation etc should be enabled by giving the following rights to group "Everyone" in queues:
AssignCustomFields
CommentOnTicket
CreateTicket
ModifyTicket
ReplyToTicket

</pre>
